home *** CD-ROM | disk | FTP | other *** search
/ Aminet 15 / Aminet 15 - Nov 1996.iso / Aminet / dev / gcc / ixemsdk.lha / man / cat3 / newctime.0 < prev    next >
Text File  |  1996-09-02  |  7KB  |  199 lines
  1.  
  2.  
  3.  
  4. NEWCTIME(3)                                           NEWCTIME(3)
  5.  
  6.  
  7. NNAAMMEE
  8.        asctime, ctime, difftime, gmtime, localtime, mktime - con-
  9.        vert date and time to ASCII
  10.  
  11. SSYYNNOOPPSSIISS
  12.        eexxtteerrnn cchhaarr **ttzznnaammee[[22]];;
  13.  
  14.        vvooiidd ttzzsseett(())
  15.  
  16.        ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
  17.  
  18.        cchhaarr **ccttiimmee((cclloocckk))
  19.        ccoonnsstt ttiimmee__tt **cclloocckk;;
  20.  
  21.        ddoouubbllee ddiiffffttiimmee((ttiimmee11,, ttiimmee00))
  22.        ttiimmee__tt ttiimmee11;;
  23.        ttiimmee__tt ttiimmee00;;
  24.  
  25.        ##iinncclluuddee <<ttiimmee..hh>>
  26.  
  27.        cchhaarr **aassccttiimmee((ttmm))
  28.        ccoonnsstt ssttrruucctt ttmm **ttmm;;
  29.  
  30.        ssttrruucctt ttmm **llooccaallttiimmee((cclloocckk))
  31.        ccoonnsstt ttiimmee__tt **cclloocckk;;
  32.  
  33.        ssttrruucctt ttmm **ggmmttiimmee((cclloocckk))
  34.        ccoonnsstt ttiimmee__tt **cclloocckk;;
  35.  
  36.        ttiimmee__tt mmkkttiimmee((ttmm))
  37.        ssttrruucctt ttmm **ttmm;;
  38.  
  39.        cccc ...... --llzz
  40.  
  41. DDEESSCCRRIIPPTTIIOONN
  42.        _C_t_i_m_e converts a long integer, pointed to by _c_l_o_c_k, repre-
  43.        senting the time in seconds since 00:00:00 UTC, January 1,
  44.        1970, and returns a pointer to a  26-character  string  of
  45.        the form
  46.                       Thu Nov 24 18:22:48 1986\n\0
  47.        All the fields have constant width.
  48.  
  49.        _L_o_c_a_l_t_i_m_e and _g_m_t_i_m_e return pointers to ``tm'' structures,
  50.        described below.  _L_o_c_a_l_t_i_m_e corrects for the time zone and
  51.        any time zone adjustments (such as Daylight Saving Time in
  52.        the U.S.A.).   After  filling  in  the  ``tm''  structure,
  53.        _l_o_c_a_l_t_i_m_e  sets  the  ttmm__iissddsstt'th  element  of ttzznnaammee to a
  54.        pointer to an ASCII string that's the time zone  abbrevia-
  55.        tion to be used with _l_o_c_a_l_t_i_m_e's return value.
  56.  
  57.        _G_m_t_i_m_e converts to Coordinated Universal Time.
  58.  
  59.        _A_s_c_t_i_m_e converts a time value contained in a ``tm'' struc-
  60.        ture to a 26-character  string,  as  shown  in  the  above
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. NEWCTIME(3)                                           NEWCTIME(3)
  71.  
  72.  
  73.        example, and returns a pointer to the string.
  74.  
  75.        _M_k_t_i_m_e  converts  the broken-down time, expressed as local
  76.        time, in the structure pointed to by _t_m  into  a  calendar
  77.        time  value  with  the same encoding as that of the values
  78.        returned by the _t_i_m_e function.  The original values of the
  79.        ttmm__wwddaayy  and  ttmm__yyddaayy  components  of  the  structure  are
  80.        ignored, and the original values of the  other  components
  81.        are not restricted to their normal ranges.  (A positive or
  82.        zero value for ttmm__iissddsstt causes _m_k_t_i_m_e to presume initially
  83.        that summer time (for example, Daylight Saving Time in the
  84.        U.S.A.)  respectively, is or is  not  in  effect  for  the
  85.        specified  time.  A negative value for ttmm__iissddsstt causes the
  86.        _m_k_t_i_m_e function to attempt to divine whether  summer  time
  87.        is  in effect for the specified time.)  On successful com-
  88.        pletion, the values of the ttmm__wwddaayy and ttmm__yyddaayy  components
  89.        of the structure are set appropriately, and the other com-
  90.        ponents are set to represent the specified calendar  time,
  91.        but  with  their values forced to their normal ranges; the
  92.        final value of ttmm__mmddaayy is not set until ttmm__mmoonn and ttmm__yyeeaarr
  93.        are  determined.   _M_k_t_i_m_e  returns  the specified calendar
  94.        time; If the  calendar  time  cannot  be  represented,  it
  95.        returns --11.
  96.  
  97.        _D_i_f_f_t_i_m_e  returns  the  difference  between  two  calendar
  98.        times, (_t_i_m_e_1 - _t_i_m_e_0), expressed in seconds.
  99.  
  100.        Declarations of all the functions and externals,  and  the
  101.        ``tm''  structure,  are  in the <<ttiimmee..hh>> header file.  The
  102.        structure (of  type)  ssttrruucctt  ttmm  includes  the  following
  103.        fields:
  104.  
  105.                    int tm_sec;      /* seconds (0 - 60) */
  106.                    int tm_min;      /* minutes (0 - 59) */
  107.                    int tm_hour;     /* hours (0 - 23) */
  108.                    int tm_mday;     /* day of month (1 - 31) */
  109.                    int tm_mon;      /* month of year (0 - 11) */
  110.                    int tm_year;     /* year - 1900 */
  111.                    int tm_wday;     /* day of week (Sunday = 0) */
  112.                    int tm_yday;     /* day of year (0 - 365) */
  113.                    int tm_isdst;    /* is summer time in effect? */
  114.                    char *tm_zone;   /* abbreviation of timezone name */
  115.                    long tm_gmtoff;  /* offset from UTC in seconds */
  116.  
  117.        The _t_m___z_o_n_e and _t_m___g_m_t_o_f_f fields exist, and are filled in,
  118.        only if arrangements to do so were made when  the  library
  119.        containing these functions was created.  There is no guar-
  120.        antee that these fields will continue  to  exist  in  this
  121.        form in future releases of this code.
  122.  
  123.        _T_m___i_s_d_s_t is non-zero if summer time is in effect.
  124.  
  125.        _T_m___g_m_t_o_f_f  is  the  offset (in seconds) of the time repre-
  126.        sented from UTC, with positive values indicating  east  of
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. NEWCTIME(3)                                           NEWCTIME(3)
  137.  
  138.  
  139.        the Prime Meridian.
  140.  
  141. FFIILLEESS
  142.        /usr/local/etc/zoneinfo             time  zone information
  143.        directory
  144.        /usr/local/etc/zoneinfo/localtime   local time zone file
  145.        /usr/local/etc/zoneinfo/posixrules  used with  POSIX-style
  146.        TZ's
  147.        /usr/local/etc/zoneinfo/GMT         for UTC leap seconds
  148.  
  149.        If //uussrr//llooccaall//eettcc//zzoonneeiinnffoo//GGMMTT is absent, UTC leap seconds
  150.        are loaded from //uussrr//llooccaall//eettcc//zzoonneeiinnffoo//ppoossiixxrruulleess.
  151.  
  152. SSEEEE AALLSSOO
  153.        getenv(3), newstrftime(3), newtzset(3), time(2), tzfile(5)
  154.  
  155. NNOOTTEESS
  156.        The  return values point to static data; the data is over-
  157.        written by each call.  The ttmm__zzoonnee  field  of  a  returned
  158.        ssttrruucctt  ttmm  points  to a static array of characters, which
  159.        will also be overwritten at the next call (and by calls to
  160.        _t_z_s_e_t).
  161.  
  162.        Avoid  using  out-of-range values with _m_k_t_i_m_e when setting
  163.        up lunch with promptness sticklers in Riyadh.
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.